home *** CD-ROM | disk | FTP | other *** search
/ Linux Cubed Series 3: Developer Tools / Linux Cubed Series 3 - Developer Tools.iso / devel / debugger / ups-2.003 < prev    next >
Encoding:
Text File  |  1996-11-16  |  10.2 KB  |  253 lines
  1. This is a copy of the top level README file for the ups debugger.
  2. You should find a compressed tar file containing the current
  3. release (2.45) of ups in the file ups-2.45.tar.Z in this directory.
  4.  
  5.  
  6. WHAT IS UPS?
  7. ------------
  8.  
  9. Ups is a source level C debugger that runs under X11 or SunView.
  10. It runs in a window with two major regions: one showing the
  11. current state of the target program data and the other showing
  12. the currently executing source code.  A key feature of ups is
  13. that the variables display is persistent: when you add a variable
  14. to the display it stays there as you step through the code.  The
  15. current stack trace (which function called which) is always visible.
  16.  
  17. Ups includes a C interpreter which allows you to add fragments
  18. of code simply by editing them into the source window (the source
  19. file itself is not modified).  This lets you add debugging printf
  20. calls without recompiling, relinking (or even restarting) the
  21. target program.  You can also add conditional breakpoints in a
  22. natural way - you just add a statement like "if (i == 73) #stop"
  23. at the appropriate place in the source window.
  24.  
  25. Some things you can do with ups:
  26.  
  27.    + Add variables to the display by simply clicking on them
  28.      in the source window.
  29.  
  30.    + Expand (recursively) structures and unions to show their
  31.      members.
  32.     
  33.    + Assign to variables by editing the displayed value.
  34.  
  35.    + Add breakpoints by pointing with the mouse at the line
  36.      where you want execution to stop.
  37.     
  38.    + Add interpreted code at any breakpoint, including code that
  39.      calls compiled functions and assigns to variables.
  40.  
  41. It's hard to describe an interactive application in a few paragraphs of
  42. text - the best way to see what ups is like grab a copy and try it.
  43. There's a walkthrough debugging session in the manual page: if you work
  44. through this and aren't hooked at the end of it then I'll give you
  45. your money back :-)
  46.  
  47.  
  48. HOW UPS DIFFERS FROM XXGDB, XDBX AND DBXTOOL
  49. --------------------------------------------
  50.  
  51. The key implementation difference between ups and the various X front
  52. ends for dbx and gdb is that ups is not a front end for a command based
  53. debugger.  Xdbx and xgdb give you a convenient way to invoke the
  54. underlying debugger's commands, but it is fairly clear in both that
  55. you are talking to a text based debugger.  Ups in the other hand is
  56. a complete native debugger implementation; there is no underlying
  57. command language.
  58.  
  59. An example: to print the value of a variable in xgdb you select (by
  60. dragging) a variable name and then click on `print' in the menu.  Xgdb
  61. passes the print command with the selection to gdb and displays the
  62. result.  By contract in ups you click the mouse over a variable name
  63. and it is added to the display.  Once the variable is added to the
  64. display it stays there, so you can watch it change as you step through
  65. the code.  If the variable happens to be a structure or a pointer to a
  66. structure you can `expand' it to show its members.  Again, the
  67. structure members thus added remain in the display until you get rid of
  68. them so you can watch their values change as you execute the code.
  69.  
  70. Of course there is a downside to not talking to an existing debugger: you
  71. lose portability.  Ups is machine dependent - a port to a new architecture
  72. is a significant effort.  I think the benefits outweigh the cost.
  73.  
  74.  
  75. SUPPORTED CONFIGURATIONS
  76. ------------------------
  77.  
  78. The current list of supported configurations is:
  79.  
  80.     Architecture        OS version        Window system
  81.     ------------        ----------        -------------
  82.     SPARC            SunOS 4.X        X11 or SunView 1
  83.     Sun 3            SunOS 4.X        X11 or SunView 1
  84.     Sun 386i        SunOS 4.0.X        X11 or SunView 1
  85.     DECstation        Ultrix 3.X and 4.2    X11
  86.     Intel 386        BSDI BSD/386 0.3 Beta    X11
  87.     HLH Clipper        4.3BSD            X11
  88.  
  89. [ You've never heard of the HLH Clipper.  Don't worry, you're not alone. ]
  90.  
  91. Ups has also been ported to the Sony NEWS (MIPS) workstation (by Nobuyuki
  92. Hikichi) and to the MIPS Magnum 3000 (by Hal R. Brand and Conor Doherty).
  93. I have folded these changes into the code but I don't have access to the
  94. machines to test them directly.
  95.  
  96. Ups has FORTRAN support on the Sun 3 and SPARC but this is not as
  97. stable or complete as the C support.  Ups should also work with gcc (even
  98. with the -O flag).  This is known to work pretty well on the SPARC; your
  99. mileage may vary on other systems.  Unlike earlier releases, the current
  100. version of ups works with gcc 2.X (except on the DECstation).
  101.  
  102. Ups will probably work on OS releases other than these; the list above
  103. describes the OS versions on the machines that I have access too.  In
  104. particular I have built ups for a VAX 750 running 4.3BSD and X11 - it
  105. appeared to work OK but wasn't tested thoroughly or used in anger.
  106.  
  107. Ups is unavoidably architecture and OS dependent as it knows about things
  108. like the ptrace() system call interface and object file symbol table formats.
  109. A port to a new architecture is likely to take several weeks.
  110.  
  111.  
  112. INSTALLATION
  113. ------------
  114.  
  115. Ups should be reasonably simple to install.  It has no library files,
  116. just a binary and manual page.  You can put the binary and manual
  117. pages where you like.  There is no need to be root to do any part of
  118. the installation (although you must obviously have permission to
  119. create files in the directories where you put the binary and manual page).
  120.  
  121. The steps are:
  122.  
  123. 1)  Unpack the distribution. You should have a compressed tar file called
  124.     ups-2.XX.tar.Z (where 2.XX is the version number of the release).
  125.     Change directory to a disk with a three or more megabytes of free
  126.     space and say:
  127.  
  128.      zcat ups-2.XX.tar | tar xfp -
  129.  
  130.     This will create a directory tree called ups-2.XX.  Change directory
  131.     into it.
  132.  
  133. 2)  If you wish to use imake then say "sh imake.sh" at this point
  134.     and skip to step 4.  This will unpack Imakefiles from the file
  135.     imakefiles.tar and run xmkmf to build makefiles.  The Imakefiles
  136.     were written by Rainer Klute (klute@irb.informatik.uni-dortmund.de).
  137.  
  138.     If you are building the SunView version of ups, or do not have imake
  139.     or xmkmf then skip this step and use the supplied makefiles.
  140.  
  141. 3)  Optionally edit the Makefile in this root directory.  You might want
  142.     to do this if you want to specify special flags to to compiler (for
  143.     example if your X header files live somewhere other that /usr/include/X11).
  144.     You might also want to change the default locations of the installed
  145.     binary and manual page.
  146.  
  147. 3a) If you are building ups on a Sun (of any architecture) running
  148.     SunOS 4.0.3 or earlier, uncomment the line in the Makefile in this
  149.     directory that sets SUBMAKEFLAGS to ARCH_CFLAGS=-DFIX_SHORT_PARAMS.
  150.     See the comment in the Makefile for more information.
  151.  
  152. 3b) If you are using a MIPS RISC/os machine, uncomment the SUBMAKEFLAGS
  153.     line for RISC/os.  If you are running RISCwindows then uncomment
  154.     the X11LIB line just below the SUBMAKEFLAGS line.
  155.  
  156. 4)  Type "make".  If all goes well this should build you a binary called
  157.     ups/ups.  If you want the SunView binary, say "make sunviewups".
  158.     This will produce a binary called ups/sunviewups.
  159.  
  160.     The BSDI make and sh (at least on the Beta 0.3 release) have some
  161.     bugs which are triggered by the ups makefiles.  If you are not using
  162.     imake (which also failed for me on BSDI), you can use the following
  163.     evil runes to make ups build:
  164.  
  165.          make ups/develhdrs libx11wn
  166.      make SUBMAKEFLAGS="-n | sh -x"
  167.  
  168.     If you want you can experiment with ups at this point.  The manual
  169.     page (in ups/doc/ups.man) has a "GETTING STARTED" section which
  170.     should get you going.
  171.  
  172. 5)  Type "make install".  By default this will install ups/ups as
  173.     /usr/local/X11/ups and the manual page as /usr/man/manl/ups.l.
  174.     To install the Sunview version of ups say "make sunviewinstall".
  175.     By default this will install ups/sunviewups as /usr/local/Sunview/ups.
  176.  
  177.     If you don't wish to run "make install" you can install ups simply by
  178.     copying the binary and manual page into place.
  179.  
  180.  
  181. DOCUMENTATION
  182. -------------
  183.  
  184. The following files contain documentation on ups:
  185.  
  186.     ups/doc/ups.man     The user manual page
  187.  
  188.     ups/doc/porting.ms  A guide to porting ups to a new architecture.
  189.  
  190.     README.multiarch    Description of a scheme for doing simultaneous
  191.                 builds of ups in one NFS mounted source
  192.                 directory on multiple architectures.
  193.  
  194.     lib/*/README        Brief overviews of the various libraries
  195.                 used to build ups.  Some have pointers to
  196.                 more documentation.
  197.                 
  198.  
  199. COPYING THE CODE
  200. ----------------
  201.  
  202. Feel free to copy bits of ups for your own use (caveat: you must contact
  203. me first if you want to incorporate the code into a commercial product).
  204. You must preserve the copyright notices.
  205.  
  206. Things you might find useful (despite the lack of documentation):
  207.  
  208. ups/ci_*.[cy]    A reasonably complete ANSI C interpreter.  There are many
  209.         details that it gets wrong (e.g. the exact type of integer
  210.         constants and the subtler aspects of typedefs).  There is
  211.         a test driver in ups/cx.c.  The grammar is in ups/ci_parse.y.
  212.         This was derived from the grammar at the back of K&R2.
  213.  
  214. ups/as_*.c    Disassemblers for the 68020, SPARC, VAX and MIPS chips.
  215.  
  216. lib/libmtrprog/genmergesort.h
  217.         A macro to implement a merge sort function for any linked list.
  218.  
  219. lib/libukcprog/*.c
  220.         Various low level routines that aren't in the standard
  221.         C library.
  222.  
  223. lib/libarg/*.c    General purpose command line parsing, including filename
  224.         globbing and I/O redirection.
  225.  
  226. One day I might get round to documenting all this stuff ...
  227.  
  228.  
  229. FEEDBACK
  230. --------
  231.  
  232. I hope you find ups a useful tool.  If you have problems building
  233. or using it, find bugs or have suggestions for improvements please
  234. send me mail (I am mtr@ukc.ac.uk).  Paeans of praise describing how
  235. wonderful ups is are also appreciated :-)
  236.  
  237. There is a mailing list for discussion of ups and for announcements
  238. of bug fixes and new features.  The list is ups-users@ukc.ac.uk -
  239. send requests to be added to the list to ups-users-request@ukc.ac.uk.
  240.  
  241. I'm especially interested in ports to new architectures.  There is
  242. a document (ups/doc/porting.ms) giving an overview of the implementation
  243. of ups and how to port it.  I'll be happy to give advice and help
  244. to anyone doing a port, and even happier to incorporate completed
  245. ports back into the standard release.
  246.  
  247. A personal note: I have benefited enormously from free software
  248. that others have contributed (things like perl, gcc, X and BSD).
  249. Ups is my attempt to give something back.  Long live free software.
  250.  
  251. Mark Russell
  252. mtr@ukc.ac.uk
  253.